home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kopete / kopetechatsession.h < prev    next >
Encoding:
C/C++ Source or Header  |  2006-10-01  |  12.9 KB  |  406 lines
  1. /*
  2.     kopetechatsession.h - Manages all chats
  3.  
  4.     Copyright (c) 2002      by Duncan Mac-Vicar Prett <duncan@kde.org>
  5.     Copyright (c) 2002      by Daniel Stone           <dstone@kde.org>
  6.     Copyright (c) 2002-2003 by Martijn Klingens       <klingens@kde.org>
  7.     Copyright (c) 2002-2004 by Olivier Goffart        <ogoffart @ kde.org>
  8.     Copyright (c) 2003      by Jason Keirstead        <jason@keirstead.org>
  9.     Copyright (c) 2005      by Micha├½l Larouche       <michael.larouche@kdemail.net>
  10.  
  11.     Kopete    (c) 2002-2003 by the Kopete developers  <kopete-devel@kde.org>
  12.  
  13.     *************************************************************************
  14.     *                                                                       *
  15.     * This library is free software; you can redistribute it and/or         *
  16.     * modify it under the terms of the GNU Lesser General Public            *
  17.     * License as published by the Free Software Foundation; either          *
  18.     * version 2 of the License, or (at your option) any later version.      *
  19.     *                                                                       *
  20.     *************************************************************************
  21. */
  22.  
  23. #ifndef __KOPETECHATSESSION_H__
  24. #define __KOPETECHATSESSION_H__
  25.  
  26. #include <qobject.h>
  27. #include <qptrlist.h>
  28. #include <qvaluelist.h>
  29.  
  30. #include <kxmlguiclient.h>
  31.  
  32. #include "kopete_export.h"
  33.  
  34. // FIXME: get rid of these includes
  35. #include "kopetemessage.h"
  36. #include "kopetemessagehandlerchain.h"
  37.  
  38. class KMMPrivate;
  39.  
  40. class KopeteView;
  41.  
  42. namespace Kopete
  43. {
  44.  
  45. class Contact;
  46. class Message;
  47. class Protocol;
  48. class OnlineStatus;
  49. class Account;
  50. class ChatSessionManager;
  51. class MessageHandlerChain;
  52. class TemporaryKMMCallbackAppendMessageHandler;
  53.  
  54. typedef QPtrList<Contact>   ContactPtrList;
  55. typedef QValueList<Message> MessageList;
  56.  
  57.  
  58. /**
  59.  * @author Duncan Mac-Vicar Prett <duncan@kde.org>
  60.  * @author Daniel Stone           <dstone@kde.org>
  61.  * @author Martijn Klingens       <klingens@kde.org>
  62.  * @author Olivier Goffart        <ogoffart @ kde.org>
  63.  * @author Jason Keirstead        <jason@keirstead.org>
  64.  *
  65.  * The Kopete::ChatSession manages a single chat.
  66.  * It is an interface between the protocol, and the chatwindow.
  67.  * The protocol can connect to @ref messageSent() signals to send the message, and can
  68.  * append received message with @ref messageReceived()
  69.  *
  70.  * The KMM inherits from KXMLGUIClient, this client is merged with the chatwindow's ui
  71.  * so plugins can add childClients of this client to add their own actions in the
  72.  * chatwindow.
  73.  */
  74. class KOPETE_EXPORT ChatSession : public QObject , public KXMLGUIClient
  75. {
  76.     // friend class so the object factory can access the protected constructor
  77.     friend class ChatSessionManager;
  78.  
  79.     Q_OBJECT
  80.  
  81. public:
  82.     /**
  83.      * Delete a chat manager instance
  84.      * You shouldn't delete the KMM yourself. it will be deleted when the chatwindow is closed
  85.      * see also @ref setCanBeDeleted() , @ref deref() 
  86.      */
  87.     ~ChatSession();
  88.  
  89.     /**
  90.      * @brief Get a list of all contacts in the session
  91.      */
  92.     const ContactPtrList& members() const;
  93.  
  94.     /**
  95.      * @brief Get the local user in the session
  96.      * @return the local user in the session, same as account()->myself()
  97.      */
  98.     const Contact* myself() const;
  99.  
  100.     /**
  101.      * @brief Get the protocol being used.
  102.      * @return the protocol
  103.      */
  104.     Protocol* protocol() const;
  105.  
  106.     /**
  107.      * @brief get the account
  108.      * @return the account
  109.      */
  110.     Account *account() const ;
  111.  
  112.     /**
  113.      * @brief The caption of the chat
  114.      *
  115.      * Used for named chats
  116.      */
  117.     const QString displayName();
  118.  
  119.     /**
  120.      * @brief change the displayname
  121.      *
  122.      * change the display name of the chat
  123.      */
  124.     void setDisplayName( const QString &displayName );
  125.  
  126.     /**
  127.      * @brief set a specified KOS for specified contact in this KMM
  128.      *
  129.      * Set a special icon for a contact in this kmm only.
  130.      * by default, all contact have their own status
  131.      */
  132.     void setContactOnlineStatus( const Contact *contact, const OnlineStatus &newStatus );
  133.  
  134.     /**
  135.      * @brief get the status of a contact.
  136.      *
  137.      * see @ref setContactOnlineStatus()
  138.      */
  139.     const OnlineStatus contactOnlineStatus( const Contact *contact ) const;
  140.  
  141.     /**
  142.      * @brief the manager's view
  143.      *
  144.      * Return the view for the supplied Kopete::ChatSession.  If it already
  145.      * exists, it will be returned, otherwise, 0L will be returned or a new one
  146.      * if canCreate=true
  147.      * @param canCreate create a new one if it does not exist
  148.      * @param requestedPlugin Specifies the view plugin to use if we have to create one.
  149.      */
  150.     // FIXME: canCreate should definitely be an enum and not a bool - Martijn
  151.     KopeteView* view( bool canCreate = false, const QString &requestedPlugin = QString::null );
  152.  
  153.     /**
  154.      * says if you may invite contact from the same account to this chat with @ref inviteContact
  155.      * @see setMayInvite
  156.      * @return true if it is possible to invite contact to this chat.
  157.      */
  158.     bool mayInvite() const ;
  159.  
  160.     /**
  161.      * this method is called when a contact is dragged to the contactlist.
  162.      * @p contactId is the id of the contact. the contact is supposed to be of the same account as
  163.      * the @ref account() but we can't be sure the Kopete::Contact is realy on the contactlist
  164.      *
  165.      * It is possible to drag contact only if @ref mayInvite return true
  166.      *
  167.      * the default implementaiton do nothing
  168.      */
  169.     virtual void inviteContact(const QString &contactId);
  170.  
  171.     /**
  172.      * Returns the message handler chain for the message direction @p dir.
  173.      */
  174.     MessageHandlerChain::Ptr chainForDirection( Message::MessageDirection dir );
  175.  
  176. signals:
  177.     /**
  178.      * @brief the KMM will be deleted
  179.      * Used by a Kopete::ChatSession to signal that it is closing.
  180.      */
  181.     void closing( Kopete::ChatSession *kmm );
  182.  
  183.     /**
  184.      * a message will be soon shown in the chatwindow.
  185.      * See @ref Kopete::ChatSessionManager::aboutToDisplay() signal
  186.      */
  187.     void messageAppended( Kopete::Message &msg, Kopete::ChatSession *kmm = 0L );
  188.  
  189.     /**
  190.      * a message will be soon received
  191.      * See @ref Kopete::ChatSessionManager::aboutToReceive() signal
  192.      */
  193.     void messageReceived( Kopete::Message &msg, Kopete::ChatSession *kmm = 0L );
  194.  
  195.     /**
  196.      * @brief a message is going to be sent
  197.      *
  198.      * The message is going to be sent.
  199.      * protocols can connect to this signal to send the message ro the network.
  200.      * the protocol have also to call @ref appendMessage() and @ref messageSucceeded()
  201.      * See also @ref Kopete::ChatSessionManager::aboutToSend() signal
  202.      */
  203.     void messageSent( Kopete::Message &msg, Kopete::ChatSession *kmm = 0L );
  204.  
  205.     /**
  206.      * The last message has finaly successfully been sent
  207.      */
  208.     void messageSuccess();
  209.  
  210.     /**
  211.      * @brief a new contact is now in the chat
  212.      */
  213.     // FIXME: What's 'suppress'? Shouldn't this be an enum? - Martijn
  214.     void contactAdded( const Kopete::Contact *contact, bool suppress );
  215.  
  216.     /**
  217.      * @brief a contact is no longer in this chat
  218.      */
  219.     void contactRemoved( const Kopete::Contact *contact, const QString &reason, Kopete::Message::MessageFormat format = Message::PlainText, bool contactRemoved = false );
  220.  
  221.     /**
  222.      * @brief a contact in this chat has changed his status
  223.      */
  224.     void onlineStatusChanged( Kopete::Contact *, const Kopete::OnlineStatus &, const Kopete::OnlineStatus & );
  225.  
  226.     /**
  227.      * @brief The name of the chat is changed
  228.      */
  229.     void displayNameChanged();
  230.  
  231.     /**
  232.      * @brief emitting a typing notification
  233.      *
  234.      * The user is typing a message, or just stopped typing
  235.      * the protocol should connect to this signal to signal to others
  236.      * that the user is typing if the protocol supports this
  237.      * @param isTyping say if the user is typing or not
  238.      */
  239.     void myselfTyping( bool isTyping );
  240.  
  241.     /**
  242.      * Signals that a remote user is typing a message.
  243.      * the chatwindow connects to this signal to update the statusbar
  244.      */
  245.     void remoteTyping( const Kopete::Contact *contact, bool isTyping );
  246.  
  247.     /**
  248.      * Signals that a an event has to be displayed in the statusbar.
  249.      * The chatwindow connects to this signal to update the statusbar.
  250.      */
  251.     void eventNotification( const QString& notificationText);
  252.  
  253.     /**
  254.      * @brief A contact within the chat session changed his photo.
  255.      * Used to update the contacts photo in chat window.
  256.      */
  257.     void photoChanged();
  258.  
  259. public slots:
  260.     /**
  261.      * @brief Got a typing notification from a user
  262.      */
  263.     void receivedTypingMsg( const Kopete::Contact *contact , bool isTyping = true );
  264.  
  265.     /**
  266.      * Got a typing notification from a user. This is a convenience version
  267.      * of the above method that takes a QString contactId instead of a full
  268.      * Kopete::Contact
  269.      */
  270.     void receivedTypingMsg( const QString &contactId, bool isTyping = true );
  271.  
  272.     /**
  273.      * @brief Got an event notification from a user.
  274.      * It will emit the signal eventNotification(). Use this slot in your protocols
  275.      * and plugins to change chatwindow statusBar text.
  276.      */
  277.     void receivedEventNotification(  const QString& notificationText );
  278.  
  279.     /**
  280.      * Show a message to the chatwindow, or append it to the queue.
  281.      * This is the function protocols HAVE TO call for both incoming and outgoing messages
  282.      * if the message must be showed in the chatwindow
  283.      */
  284.     void appendMessage( Kopete::Message &msg );
  285.  
  286.     /**
  287.      * Add a contact to the session
  288.      * @param c is the contact
  289.      * @param suppress mean the there will be no automatic notifications in the chatwindow.
  290.      *  (note that i don't like the param suppress at all. it is used in irc to show a different notification (with an info text)
  291.      *   a QStringinfo would be more interesting, but it is also used to don't show the notification when entering in a channel)
  292.      */
  293.     void addContact( const Kopete::Contact *c, bool suppress = false );
  294.  
  295.     /**
  296.      * Add a contact to the session with a pre-set initial status
  297.      * @param c is the contact
  298.      * @param initialStatus The initial contactOnlineStatus of the contact
  299.      * @param suppress mean the there will be no automatic notifications in the chatwindow.
  300.      *  (note that i don't like the param suppress at all. it is used in irc to show a different notification (with an info text)
  301.      *   a QStringinfo would be more interesting, but it is also used to don't show the notification when entering in a channel)
  302.      * @see contactOnlineStatus
  303.      */
  304.     void addContact( const Kopete::Contact *c, const Kopete::OnlineStatus &initialStatus, bool suppress = false );
  305.  
  306.     /**
  307.      * Remove a contact from the session
  308.      * @param contact is the contact
  309.      * @param reason is the optional raison message showed in the chatwindow
  310.      * @param format The format of the message
  311.      * @param suppressNotification prevents a notification of the removal in the chat view.  See note in @ref addContact
  312.      */
  313.     void removeContact( const Kopete::Contact *contact, const QString& reason = QString::null, Kopete::Message::MessageFormat format = Message::PlainText, bool suppressNotification = false );
  314.  
  315.     /**
  316.      * Set if the KMM will be deleted when the chatwindow is deleted. It is useful if you want
  317.      * to keep the KMM alive even if the chatwindow is closed.
  318.      * Warning: if you set it to false, please keep in mind that you have to reset it to true
  319.      *  later to delete it. In many case, you should never delete yourself the KMM, just call this
  320.      *  this method.
  321.      * default is true.
  322.      * If there are no chatwindow when setting it to true, the kmm will be deleted.
  323.      *
  324.      * @deprecated  use ref and deref
  325.      */
  326.     void setCanBeDeleted ( bool canBeDeleted );
  327.  
  328.     /**
  329.      * reference count the chat session.
  330.      * the chat session may be deleted only if the count reach 0
  331.      * if you ref, don't forget to deref
  332.      * @see deref()
  333.      */
  334.     void ref();
  335.     /**
  336.      * dereference count the chat session
  337.      * if the reference counter reach 0 and there is no chat window open, the chat session will be deleted.
  338.      */
  339.     void deref();
  340.         
  341.  
  342.     /**
  343.      * Send a message to the user
  344.      */
  345.     void sendMessage( Kopete::Message &message );
  346.  
  347.     /**
  348.      * Tell the KMM that the user is typing
  349.      * This method should be called only by a chatwindow. It emits @ref myselfTyping signal
  350.      */
  351.     void typing( bool t );
  352.  
  353.     /**
  354.      * Protocols have to call this method when the last message sent has been correctly sent
  355.      * This will emit @ref messageSuccess signal. and allow the email window to get closed
  356.      */
  357.     void messageSucceeded();
  358.  
  359.     /**
  360.      * Protcols have to call this method if they want to emit a notification when a nudge/buzz is received.
  361.      */
  362.     void emitNudgeNotification();
  363.     
  364.     /**
  365.      * Raise the chat window and give him the focus
  366.      * It's used when the user wanted to activated  (by clicking on the "view" button of a popup)
  367.      */
  368.     void raiseView();
  369.  
  370. private slots:
  371.     void slotUpdateDisplayName();
  372.     void slotViewDestroyed();
  373.     void slotOnlineStatusChanged( Kopete::Contact *c, const Kopete::OnlineStatus &status, const Kopete::OnlineStatus &oldStatus );
  374.     void slotContactDestroyed( Kopete::Contact *contact );
  375.  
  376. protected:
  377.     /**
  378.      * Create a message manager. This constructor is private, because the
  379.      * static factory method createSession() creates the object. You may
  380.      * not create instances yourself directly!
  381.      */
  382.     ChatSession( const Contact *user, ContactPtrList others,
  383.         Protocol *protocol, const char *name = 0 );
  384.  
  385.     /**
  386.      * Set wether or not contact from this account may be invited in this chat.
  387.      * By default, it is set to false
  388.      * @see inviteContact()
  389.      * @see mayInvite()
  390.      */
  391.     void setMayInvite(bool);
  392.  
  393. private:
  394.     KMMPrivate *d;
  395.  
  396.     // FIXME: remove
  397.     friend class TemporaryKMMCallbackAppendMessageHandler;
  398. };
  399.  
  400. }
  401.  
  402. #endif
  403.  
  404. // vim: set noet ts=4 sts=4 sw=4:
  405.  
  406.